Subscriptions: Suppressions

Subscriptions: Suppressions

#340730

Description

The /subscriptions/<platformType>/suppressions resource is used to store a list of attribute tags and recommendation properties available to the Subscriptions resource for the purpose of suppressing specific sets of system recommendations from the resulting subscription data set.

This resource acts as a catalog of the suppression tags or properties to be referenced by the suppressionReferences parameter in the Subscriptions resource . Suppression entries (tags or properties) not defined in a /subscriptions/<platformType>/suppressions resource cannot be referenced; you must define the suppression entries before using them in a suppression condition. See Subscriptions for details on defining a subscription.

There is a catalog for each supported <platformType>, which can only be referenced by the corresponding <platformType> subscription. For example, a container subscription (i.e. /subscriptions/containers) can only reference suppressions from the Container Subscriptions Suppressions catalog (i.e. /subscriptions/containers/suppressions).

Suppression entries can be declared as global or private (i.e. user-specific). Global suppression entries can be used by any API enabled user, while private entries can only be used by their owners. Note that administrative usersClosed An administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. have access to all suppression entries - global or private user-specific.

Resource

/subscriptions/cloud/suppressions

/subscriptions/containers/suppressions

/subscriptions/suppressions

Note: If you use this resource without the <platformType> specified (i.e. without cloud or containers specified), the behavior is exactly the same as specifying the cloud-specific resource. This behavior enables backward compatibility with scripts using the Densify API prior to release 12.1.6, where the platform-specific indicator was not available.

Supported Operations

Table: Subscriptions Suppressions Supported Operations

HTTP Method

Input

Output

Description

GET /subscriptions/<platformType>/suppressions

Path Parameter:

Query String Parameter Options:

Collection of

Returns a list of existing suppression tags or properties from the platform-specific Subscriptions Suppressions catalog.

See Example: Getting a List of Available Cloud Subscriptions Suppressions.

GET /subscriptions/<platformType>/suppressions/ <suppressionRef>

Path Parameters:

Returns a Subscriptions suppression with unique identifier <suppressionRef> from a platform-specific Subscriptions Suppressions catalog.

See Example: Getting a Specific Container Subscriptions Suppression.

POST /subscriptions/<platformType>/suppressions

Path Parameter:

Collection of

Request Body Parameters:

Collection of

See Example: Adding New Subscription Suppressions.

Adds new suppression entries into a platform-specific Subscriptions Suppressions catalog.

A suppression entry can be either a tag or a property suppression. You can specify an attributeName or a propertyName, but not both.

PUT /subscriptions/<platformType>/suppressions

Path Parameter:

Request Body Parameters:

Collection of

Collection of

Deletes and replaces parameters for existing suppression entries in a platform-specific Subscriptions Suppressions catalog.

You must specify all parameters (except suppressionRef) required for the suppression you want to update.

See Example: Modifying Subscription Suppressions.

PUT /subscriptions/ suppressions/<suppressionRef>

Path Parameters:

Request Body Parameters:

Deletes and replaces parameters for an existing suppression entry identified by <suppressionRef> in a platform-specific Subscriptions Suppressions catalog.

You must specify all parameters required (in the Request Body Parameters section) for the suppression you want to update, as all previous parameters are deleted.

See Example: Modifying a Subscription Suppression.

DELETE /subscriptions/<platformType>/suppressions

Path Parameter:

Collection of

  • HTTP status of "204 No Content" if all delete operations are successful
  • If delete errors occur, the following is returned for each delete suppression request:

See Example: Deleting Subscriptions Suppressions.

Deletes suppressions from a platform-specific Subscriptions Suppressions catalog.

DELETE /subscriptions/<platformType>/ suppressions/ <suppressionRef>

Path Parameters:

  • HTTP status of "204 No Content" if delete operation is successful;
  • HTTP status of "404 Not Found" if suppression is not found;
  • If the suppression is referenced by a subscription, or if there are other errors, then the following is returned:

Deletes a suppression with <suppressionRef> identifier from a platform-specific Subscriptions Suppressions catalog.

Parameters

Path Parameters

Table: Subscriptions Suppressions Path Parameters

Parameter Name

Type

Required (Y/N)

Description

platformType

string

Y

[cloud|containers]

Specify the technology platform for the Subscriptions suppression resource.

suppressionRef

string

Y

Specify the unique identifier for a Subscriptions suppression entry.

Query String Parameters

Table: Subscriptions Suppressions Query String Parameters

Parameter Name

Type

Required (Y/N)

Description

type

string

 

Specify the type of Subscriptions suppression to return:

  • all—Return all suppression entries: global and private user-specific. If you are not an administrative userClosed An administrative user is a Densify user in the Administrator user group or with the Analysis Admin role., only private suppressions owned by you and global suppressions are returned. This is the default behavior if type is not specified in the request.
  • global—Return all global Subscriptions suppression entries.
  • owner—Return user-specific Subscriptions suppression entries. If you are not an administrative user, only private suppressions owned by you are returned. If you are an administrative user, all global and private suppressions are returned.

A Subscriptions suppression is considered global if the owner parameter is not populated. Global Subscriptions suppressions can be used by all Densify API users.

A Subscriptions suppression is considered private if the owner parameter contains a Densify username. Private Subscriptions suppressions can only be used by their owners or administrative users.

owner

string

 

If you are an administrative userClosed An administrative user is a Densify user in the Administrator user group or with the Analysis Admin role., you can specify a Densify username in conjunction with the type=owner query string parameter to return all of the specified user's private Subscriptions suppressions.

If you are not an administrative user, you can request for your own private suppressions. If you use the ?type=owner&owner=<anotherusername> query string option with a username other than your own, the returned response is a 400 Bad Request -"Current login user cannot query for owner" error.

Request Body Parameters

Table: Subscriptions Suppressions Request Body Parameters

Parameter Name

Type

Required (C-create/M-modify/D-delete)

Description

suppressionRef

string

M D

Specify the unique identifier for a Subscriptions suppression entry.

suppressionName

string

C M

Specify a unique name for a Subscriptions suppression entry.

For global Subscriptions suppressions, the suppressionName must be unique within a platform-specific Subscriptions Suppressions catalog. For private Subscriptions suppressions, the suppressionName must be unique per owner and across all global subscription suppressions per platform-specific catalog. For example, owner A and owner B can both have a private suppression named "SuperA", as long as "SuperA" is not also a global suppression within the same platform-specific catalog.

aliasName

string

 

Specify an alias name for the Subscriptions attribute tag.

For global suppressions, the aliasName must be unique within a platform-specific Subscriptions Suppressions catalog. For private suppressions, the aliasName must be unique per owner and across all global suppressions per platform-specific catalog. For example, owner A and owner B can both have a private suppression alias named "Joe", as long as "Joe" is also not a global suppression alias within the same platform-specific catalog.

attributeName

string

C M

Specify the attribute name for the Subscriptions suppression entry.

The attribute name must exist in the Densify standard set of system attributes. Contact [email protected] for a list of available system attributes.

Use the "Resource Tags" attribute name along with key and technology parameters for cloud technology-specific resource attributes in the "key:value" form. See Example: Adding New Subscription Suppressions for "Resource Tags" usage.

Use the "Container Labels" attribute name along with key and technology parameters for container-specific attributes in "key:value" form.

Note that the attributeName must be unique in a platform-specific Subscriptions Suppressions catalog (i.e. you cannot have two suppressions with the same attributeName in a catalog).

key

string

CM1

Specify the key string required for the technology platform resource attribute.

If the Subscriptions suppression is a reference to a resource attribute (i.e. "attributeName": "Resource Tags" or "attributeName": "Container Labels"), you need to specify both the key and technology platform for the specific resource attribute.

technology

string

CM2

Specify the technology platform for the resource attribute. Currently, the following technology platforms are supported:

  • AWS
  • CONTAINER

If the Subscriptions suppression is a reference to a resource attribute (i.e. "attributeName": "Resource Tags" or "attributeName": "Container Labels"), you need to specify both the key and technology platform for the specific resource attribute.

propertyName

string

C M

Specify the recommendation element for the Subscriptions suppression.

The list of available recommendation elements can be found in the Analysis: technology-specific Recommendations page. For example, refer to the Response schema section of the Analysis: AWS Recommendations for a full list of AWS recommendation elements.

The propertyName must be unique within a platform-specific Subscriptions Suppressions catalog.

owner

string

M3

When the owner parameter is not set, the Subscriptions suppression is considered global. Global Subscriptions suppressions can be used by all API users. Only administrative usersClosed An administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. can create global suppressions. When the owner parameter is set, the suppression is considered private. Private Subscriptions suppressions can only be used by their owners or administrative users.

If you are an administrative user, you have the ability to assign any Densify user as the owner of the subscription suppression in a POST request. In a PUT request, administrative users can promote the suppression from private to global by setting owner: "".

If you are not an administrative user, you can only set the owner parameter to your Densify username. In a POST request, the owner parameter is automatically populated with your username.

Response

The following is a complete list of possible response elements that are returned for the /subscriptions/suppressions resource.

Table: Subscriptions Suppressions Response Schema

Element

Type

Filter/Sort

Description

suppressionRef

string

 

The unique referenced ID of the Densify Subscriptions suppression entry.

suppressionName

string

 

The Subscriptions suppression name.

aliasName

string

 

The Subscriptions suppression alias name.

attributeName

string

 

The attribute name for the Subscriptions suppression entry.

technology

string

 

The Subscriptions suppression's technology platform for the resource attribute.

key

string

 

The resource attribute key string for the suppression's associated technology platform.

propertyName

string

 

The Subscriptions suppression property name.

owner

string

F

The designated user/owner of this Subscriptions suppression.

A Subscriptions suppression is considered global if the owner parameter is not populated. Global Subscriptions suppressions can be used by all Densify API users.

A Subscriptions suppression is considered private if the owner parameter contains a Densify username. Private Subscriptions suppressions can only be used by their owners or administrative usersClosed An administrative user is a Densify user in the Administrator user group or with the Analysis Admin role..

message

string

 

The message for the error or status response is returned.

status

number

 

The HTTP response code of the request. Possible status values include:

  • 200—success with request (usually with content in response body);
  • 204—success with request, no content returned;
  • 400—bad request (invalid parameters, logical errors);
  • 401—authentication failed;
  • 404—resource not found (or no privileges);
  • 415—unsupported media type;
  • 500—internal server error.

Examples

Example: Getting a List of Available Cloud Subscriptions Suppressions

The following example shows you how to retrieve a list of suppressions available to you from the Cloud Subscriptions Suppressions catalog.

Example: Getting a Specific Container Subscriptions Suppression

The following example shows you how to retrieve a specific container Subscriptions suppression with a known reference ID. This suppression must be of type "global" or owned by you before a successful response is returned.

Example: Adding New Subscription Suppressions

This example shows you how to add new suppression entries to the Cloud Subscriptions Suppressions catalog. Notice that the owner parameter is not set. If you are a non-administrative Densify user authenticating the POST request, the owner parameter is automatically set to your username. By having the owner parameter set, the suppression is considered private and can only be used by you (or any administrative user). If you are a Densify administrative userClosed An administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. and you do not set the owner parameter in the POST request, then the suppression is considered global.

If there is an error in the POST request resulting from any one of the suppression additions, then all the suppression additions in the request body are rolled back and not committed.

Example: Modifying Subscription Suppressions

This example shows you how to modify two subscription suppression entries in the Cloud Subscriptions Suppressions catalog. You need to specify all the request body parameters for PUT request. With the exception of the suppressionRef and owner parameters, all other parameters can be updated If there is an error in the PUT request from any one of the update entries, then all the updates are rolled back and not applied. Note that only the administrative user is eligible to make this PUT request.

Example: Modifying a Subscription Suppression

This example shows you how to modify a single cloud Subscriptions suppression using the /subscriptions/cloud/suppressions/<suppressionRef> resource. You need to specify all the request body parameters for a PUT request, even if you only want to modify the suppressionName or aliasName parameters. In this example, you must either be the "saas" user or the administrative user to be authorized to make this PUT request.

Example: Deleting Subscriptions Suppressions

This example shows you how to delete a collection of suppressions from the /subscriptions/cloud/suppressions resource catalog. Keep in mind that you can only delete your own private suppressions from the catalog. Only administrative usersClosed An administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. can delete any global and any private suppressions.

Default Suppressions